The Atari Compendium

home *** CD-ROM | disk | FTP | other *** search

/ The Atari Compendium / The Atari Compendium (Toad Computers) (1994).iso / files / umich / telecomm / storm100.lzh / BASIC.DOC next >

Wrap

Text File | 1993-11-03 | 68KB | 1,934 lines

Basic language overview This document assumes you are already familiar with the Basic language. Its purpose is to explain the special features of Storm Basic. Storm Basic is a Basic language interpreter with extensions to handle the serial port, file transfer, and other Storm functions. It does not have floating point or graphics features. Variables: You can only have 128 total variables. There is no fixed limit on the length of a variable name, as long as it fits on a single line. Upper and lower case ARE significant in variable names. You can use the same variable name for an integer, an integer array, a string, and a string array. e.g. in: DIM x(10),x$(10) x = LEN(x$) there are actually four separate variables. Math functions: The usual math operations are supported. e.g. addition, subtraction, multiplication, division and MOD (modulus function) and the Boolean functions XOR, NOT, AND and OR. The comparision operators >, <, >=, <= and <> are supported. In accordance with typical Basic practice, TRUE is -1 and FALSE is 0. Arrays: Each element of an array, whether string or integer, requires four bytes of overhead. The maximum array space available is 64K. That means that the maximum number of array elements is limited to a combined total of 16384. Arrays can have one or two dimensions only. Trying to dimension more than two array dimensions will cause a syntax error. Memory: Basic allocates memory as required and releases it when no longer required. Each Basic string or element of a string array is allocated separately and can be up to 64K long. The total amount of string memory is limited to approximately 638K, which should be enough for even the most demanding programs. The total size of a Basic program is limited only by available memory. However, the total number of lines in a program must not exceed 64K. Labels There are no line numbers in Storm Basic. You can use line numbers if you wish, but they are treated as labels, which means they don't have to be in numeric order. Labels must be at the beginning of a line and are followed immediately by a colon ':' (except if the label consists entirely of digits). Not surprisingly, a label cannot be a Basic command, however Basic can distinguish a label such as GOTOX from the Basic statement GOTO X, which must contain a space between the GOTO and the X. You can indent lines and the indentation will be preserved. If you wish to indent a line starting with a label, add spaces AFTER the label. All spaces appearing before a label are automatically removed. Labels normally start with a letter, and contain letters, digits, or the underscore character. An exception is line numbers, which don't require a colon and are treated in all other respects as labels. Upper and lower case are significant in labels, and labels may not be longer than 31 characters. Loading and saving Basic programs Basic programs can be loaded and saved in two formats, Ascii or tokenized. Tokenized format is compressed and loads faster. However, if I add or change commands in Storm Basic the token numbers change and a new version will not be able to load old version tokenized files. "Save" in the Basic menu or as a Basic command saves in tokenized format. To save in Ascii format either use the Basic command LIST "Filename" or select "Save" from the File menu WHEN IN THE BASIC EDITOR ONLY. "Load" as a Basic command, or from the Basic menu will load either type of Basic file. Editing your Basic program. To edit a Basic program just select "Edit" from the Basic menu. A new editing window will be created with the program currently in memory displayed there. If there is no program loaded, you will get a blank editing window to create a new program. The editing window is a full text editor. You can load, save, and cut and paste to the clipboard. Note: Use the File menu Load and Save while in the Basic editor, not the Basic menu Load and Save (they only load and save to the Basic interpreter, not the Basic editor). When you have finished editing the Basic program you have two choices. Clicking on the close box of the Basic editor window will reload the program into the Basic interpreter. Any syntax errors will be flagged at this time. Or, you can select "Abort Edit" from the Basic menu and the editing window will be closed and the program in the Basic interpreter will not be updated. The Basic editor will NOT detect errors as you enter code, only when you close the window and transfer the program back to the Basic interpreter. While you are editing the Basic program, you can still use the Basic interpreter to run programs, or even load and run new program. However, when you close the Basic editing window, any program in the interpreter will be halted and replaced with the program in the Basic editing window. Syntax errors: Syntax errors will indicate a line number. In this context, the program is numbered internally starting with line 1. So if you get syntax errors and move to the editing window, refer to the line number in the information line to see which line of code generated the error. AUTOEXEC.BAS When Storm first runs, it looks for a file named AUTOEXEC.BAS in the current directory (the one that Storm was run from). If found, this Basic program automatically loads and runs. ============================================================= Basic Commands ABORT XFER Aborts a file transfer, if one is in progress. APPEND CAPTURE APPEND CAPTURE "filename" appends the capture buffer to the specified file. BAUD nn Sets baud rate to value nn, where nn is a valid baud rate value. (Range 50 to 19200) BREAK ON BREAK OFF BREAK / These commands set the hardware break bit in the serial port. To send a break, use BREAK ON:PAUSE 0:BREAK OFF. Use a longer pause for a longer break. To program this into a Storm function key as shift clr/home, add the following to the STORMKEY.INI file. [34737] UseBasic=1 Key="BREAK ON:PAUSE 0:BREAK OFF:END" If you find the break is not recognized, try a longer pause, e.g. Key="BREAK ON:PAUSE 1:BREAK OFF:END" This function works on all TT, MegaSTE and Falcon serial ports. CAPTURE ON CAPTURE OFF Turn text capture on or off. CAPTURE / Toggle text capture from on to off or vice versa. CARRIER ON CARRIER OFF CARRIER CLEAR Enables or disables carrier detect event trapping, or removes a carrier event trap entirely. This function works on all TT, MegaSTE and Falcon serial ports. Event trapping is discussed in full elsewhere. CD "path" Sets default path to "path". "path" can be a simple quoted string or any Basic string expression. This is generally used in conjunction with the Basic DIR, KILL and other statements which access the file system and would otherwise require a full filename. Path should end with a backslash '\'. CHAIN CHAIN "filename" Basic allows chaining to a new copy of the Basic interpreter. You can also specify an optional Basic file to be executed in the new interpeter. When you execute the CHAIN command, the currently running Basic program is suspended and the newly created Basic interpeter starts running. You will see that the Basic window title changes to reflect the level of chaining, e.g. Basic <2>, Basic <3>, etc. To exit to the previous Basic, it is only necessary to execute the END command. The program will continue with the statement following the CHAIN command. The level of chaining is only limited by available memory. Each new Basic interpreter has less than 1K of memory overhead. It is not possible to share variables between the original Basic interpreter and a chained Basic. However, you can use the Basic SET statement in combination with the SET$ and SET functions to save and retrieve numbers and strings in the STORM.INI and other profile files. CLIP ON CLIP OFF CLIP STOP CLIP CLEAR Enables or disabled clipboard event trapping, or removes a clipboard event trap entirely. Clipboard event trapping is described elsewhere. CLOSE #n Closes a file previously opened with the OPEN statement. Attempts to close a file twice or using an invalid file number will not cause an error, they will just be ignored. CLR Sets all integer variables to zero, undimensions all arrays, and frees all Basic strings. CLS Clears the Basic window. COM ON COM OFF COM STOP COM CLEAR Enables or disabled serial port event trapping, or removes a serial port event trap entirely. Serial port event trapping is described elsewhere. COMINPUT var$ COMINPUT var$,FULL COMINPUT var$,HALF COMINPUT is used to read data from the serial port into a string variable. All available data (up to a maximum of 256 characters) is read into the string variable. If no serial data is present, the variable is set to an empty string. By default, serial data read using this command is not displayed on the terminal screen. The optional parameter "HALF" causes serial input to be echoed to the terminal screen. The optional parameter "FULL" causes both echo to the terminal screen AND echo back to the sender. Do NOT have half duplex set when using "FULL" or you may get stuck in an infinite loop! In order to use this command, you must specify TERM OFF beforehand or else the regular terminal routines will steal some of the characters. CONT Continues execution of a Basic program that has been interrupted either with the STOP command or the UNDO key or the Basic menu "Break" item. DATA Used at the start of a statement to indicate Basic Data items. Data items can consist of numbers or strings, separated by commas. Strings which contain leading or trailing blank spaces, commas, or colons should be in double quote marks. Basic will actually add double quote marks to all strings in data statements automatically. Data statements can be mixed with other statements by separating the Data statement from the next statement with a colon. However, it is more efficient to group data statements together. DIM Allows dimensioning of Basic arrays, e.g. DIM x(2),a$(2) defines two arrays, one integer and one string. The number inside the bracket is the maximum array index. Since arrays start at element zero, a value of two means a total of three elements in the array. Basic allows integer or string arrays. The maximum number of arrays dimensions is two. Arrays may not be redimensioned. However, you can use a variable or expression to dimension an array. e.g. DIM x(a+b-1). DIR DIR "string" Prints out the files in the current directory (set by CD). An optional string lets you restrict the file listing using wildcards. e.g. DIR "*.PRG" will list all files ending in ".PRG". To get a directory listing into Basic string variables, you need to use the FSFIRST$ and FSNEXT$ functions rather than DIR. DTR ON DTR OFF Turns the DTR signal line in the serial port on or off. Useful for forcing a modem to disconnect. DTR stands for Data Terminal Ready. Most modems require DTR to be on before they will operate. It is possible to defeat this feature in most modems and ignore the state of the DTR line. This function works on all TT, MegaSTE and Falcon serial ports except for the TT Serial 1 port, due to lack of documentation. Example: To force a modem to disconnect, turn DTR off, pause briefly, then turn DTR back on again. DTR OFF PAUSE 2 DTR ON DUPLEX FULL DUPLEX HALF DUPLEX / Switches duplex to full or half, or toggles duplex between full and half. Full duplex refers to the ability for each end to send and receive at the same time. Half duplex means that communication can only occur in one direction at a time. However, true half duplex is almost never encountered today and the meaning of full and half duplex has changed somewhat. Full duplex is applied to host systems that echo back each character sent to them, while half duplex is the term applied to host systems that do not echo characters sent to them, thus requiring the local terminal to echo characters to the screen. By this definition, GEnie is a half duplex service, even though subscribers are connected using modern full-duplex modems. EDIT This command lets you edit the current Basic program in a separate full-screen window. You can cut and paste from the clipboard and load and save the Basic program as an Ascii file or as a tokenised Basic file. ELSE Only used in conjunction with the IF statement. If the condition tested in the IF statement is false, executing passes to the statement following the ELSE command. IF/ELSE/THEN/ENDIF are discussed later. END Terminates executing of a Basic program. Returns to the Ready prompt. If the program is chained from a previous Basic interpeter, control returns to the previous program and continues with the statement following the CHAIN command. ENDIF Marks the end of a multi-line IF ... THEN ELSE statement block. ENDIF must be the first statement on a line (it may be preceded by a label). Each ENDIF must be matched by the appropriate IF...THEN ELSE statement. Note that ENDIF is a single word. END IF is not the same as ENDIF. ENVIRON "aaa=bbb" Allows you to set environment strings for use by external programs run from Basic. Environment strings are always consist of a name, followed directly by an equals sign, then the value associated with that name. Environment strings are used by command shells, compilers, and various command line utilities. You will need to refer to the documentation of the program you want to run from Basic to determine if it uses or needs environment strings (also referred to as environment variables). However, the use of the environment on the Atari ST is not nearly as common as it is on MS-DOS systems. EXEC mode,"FILENAME","cmdline" Command used to execute external programs from within Basic. This is generally used for .TTP type utility programs that may need a command line. Storm will close and delete its windows, remove its menu bar, clear the screen, hide the mouse, and display the TOS cursor before running the program. After running the program, the windows, mouse, and menu bar will be restored. A few ill-behaved programs may leave the system or mouse in an unknown state. With TOS 1.4 and later, Storm uses the GEM wind_new call which should clean up after these programs. For earlier TOS versions, Storm will try to set the mouse to a known state using published line a variables, and destroy any replacement desktop. However, Storm will not attempt to close any open windows, in case they were left open by a desk accessory. Note that executing an external program during a file transfer may cause the file transfer to eventually time out. In general, you should not execute an external program during a file transfer. With programs that don't require a command line, just use "" as the command line argument. Mode should be 0 for all GEM versions except MultiTOS. With MultiTOS you can use a mode of 100 to launch a program and then keep Storm running without waiting for the program to exit. Both programs will multitask when using mode 100. FAST ON FAST OFF Normally Storm Basic checks for GEM events after each Basic statement. FAST ON disables this event checking, except when executing a GOTO, GOSUB or any other command that causes control to switch to another line. This increases the speed of execution, however you cannot abort the program, switch to another window, or use any GEM features while FAST is in effect. This is not quite as restrictive as it sounds. Most programs do contain statements that switch control to another line. Also, during WAIT, PAUSE, INPUT, KEYINPUT, DLOAD, ULOAD, and POPUP commands full GEM event handling occurs because Basic is in a suspended state during those commands. FKEY nnn,"string" Assigns a string to a function key or Alt key. The number n specifies which key is affected. For function keys F1 to F10 use the numbers 1 through 10. For Shifted function keys F1 to F10, use the numbers 11 through 20. The cursor keys numbers are as follows: 51 is Up 55 is Shift-Up 52 is Down 56 is Shift-Down 53 is Right 57 is Shift-Right 54 is Left 58 is Shift-Left The reason the cursor keys are fairly high numbers is in case I decide to add support for control and alt function keys in the future. To assign a string to a key and have it interpreted as a Basic command, add 200 to the key number,for both function keys and cursor keys. If you need to use quotation marks (") inside a function key definition, CHR$(34) can be used for this purpose. Example: FKEY 201,"PRINT "+CHR$(34)+"This is F1"+CHR$(34) defines (Basic) function key F1 as the Basic command: PRINT "This is F1" To define ALT-key macros with this command, use the Ascii key value as the key number. Example: FKEY ASC("A"),"BAUD 1200" Rather than look up the Ascii key value of "A" in a table, let Basic do the calculation for you with the ASC function which returns the Ascii value of a letter. It is also possible to define an ALT-key macro which is NOT a Basic command, something which you can't do with the Alt-Key dialog. Just use the Ascii value of the lower case key. Example: FKEY ASC("a"),"This is Alt A" FOR Statement starting a FOR ... NEXT loop. There is one peculiarity of FOR NEXT statements in Storm Basic. The loop will always execute at least once, no matter what the start and end values are set to. GEM mode,"FILENAME","cmdline" GEM is similar in effect to EXEC, except that it leaves the mouse on and doesn't turn the TOS cursor on. A command line is still required. A few GEM programs will accept a command line. Most GEM programs require the current path and drive to be set to their home directory in order to load their resource files. You should use the Basic CD command to set the appropriate path before using GEM OR pass a fully specified filename, which will cause Storm to set the current path and drive to that path. Storm will save and restore the previous path and drive when executing this command. Notes on GEM and EXEC with MultiTOS. The behaviour of GEM and EXEC with MultiTOS is different from regular TOS. Windows are NOT closed because it is possible to launch another program and then continue to run Storm. GOSUB label Jumps to a subroutine at the indicated label. The label must exist or an error will occur at run time. Line numbers are not required in Storm Basic, though Storm Basic will accept line numbers. Return from a subroutine is by means of the RETURN statement. If you do wish to exit from a GOSUB without using the RETURN statement, you should use the POP statement to remove the return address from the Basic stack. GOTO label GOTO transfers control unconditionally to a line with the indicated label. If the label doesn't exist, an error will occur at run time. HELP topic Searches the HELP.INI file for information on a topic and prints any help information in the Basic window. There is no need to use quote marks around the topic name. You cannot have any other Basic commands on the same line as the Help command. HELP HELP lists the available help topics. HELP.INI is the help file. It is like the other profile files in that each help topic is enclosed in square brackets. However, the text between each topic is plain Ascii text. The only restriction is that help text should not start with a square bracket so it won't be mistaken for a new topic. Help topics MUST be all uppercase in the HELP.INI file. You can edit the HELP.INI file in Storm and customize it as you wish. If you don't want online help, just delete or rename HELP.INI. IF Starts a conditional statement. There are two forms of the IF statement in Storm Basic. The first form is the single line form. Example: IF X > 10 THEN PRINT "X > 10" ELSE PRINT "X <= 10" The IF statement requires a THEN statement at all times. The THEN statement can be followed by any Basic statement, or by a line label. You can also use the ELSE statement after the IF THEN block to indicate what action to take if the condition tested by the IF statement is false. The ELSE statement can also be followed by a line label. Note that if a line label follows a THEN or ELSE statement, no GOTO is required. Also, any statement following the line label will be ignored because control has already been transferred to the new line. e.g. IF X > 10 then Label:print "This never gets executed" The second form is the multiline IF THEN ELSEIF statement: IF expr THEN {statements} ... ELSE {statements} ... ENDIF In the multiline IF/THEN statement, the IF must be the first statement in the line and the THEN must be the last statement, to be recognized as starting a multi-line IF/THEN sequence. (However, a label and/or spaces may appear before the IF.) The ELSE and ENDIF also must appear at the start of a line. (May be preceded by a label and/or spaces.) IF/ELSE/ENDIF may be nested. An ELSE or ENDIF without a matching IF will be flagged as a syntax error. Note:The 'ELSE IF' statement is NOT supported in Storm Basic. INPUT variable INPUT "prompt";variable Prompts the user for input in the Basic window. The standard prompt is a question mark. You can add an optional quoted string which will appear in front of the question mark. While Storm is waiting for input, all other program functions can be accessed. You can even switch away from the Basic window to another window. Event trapping is disabled during INPUT processing. 'Variable' can be any Basic variable, including an array reference. INPUT #n,variable This form of the INPUT command is for reading data from a file into a Basic variable. 'n' represents a valid file number The file must previously been opened with the Basic OPEN command. Using an invalid file number causes an error. KEYINPUT X$ Waits for you to press a key in the terminal window and then returns that key in the string variable. Works only in the terminal window. However, if you are using typeahead, it will return characters from the typeahead at the point that they are transmitted out the serial port. If keyboard macros are active, KEYINPUT reports the characters in the macro one by one, rather than reporting the keystroke that generated the macro. There is no action if the keystroke doesn't generate any serial port output, e.g. unassigned function keys. For proper operation, use TERM OFF before the KEYINPUT command to prevent missing any characters. KILL "filename" Deletes the specified file(s) from the disk. Wildcards are allowed. Use caution with this command, especially with wildcards. LET A seldom used keyword. Can be used in front of assigment expressions. e.g. LET x = 1 LFEED ON LFEED OFF LFEED / LFEED ON causes a line feed to be generated internally every time a Carriage Return character is received. LFEED OFF turns this feature off. LFEED / toggles the line feed setting between on and off. LINE INPUT var$ LINE INPUT "prompt";var$ Reads an entire line of input from the Basic window into a string variable. You can optionally select a prompt to be displayed. LINE INPUT #n,var$ Reads an entire line of input from a file into a string variable. The line ends when a line feed is encountered, or 255 characters have been read, whichever comes first. You should open an Ascii file in text mode (see OPEN) for proper results using this statement. LIST LIST "filename" LIST label1,label2 LIST label LIST by itself lists the current program in the Basic window. LIST "filename" saves the current program to the file "filename" as an Ascii file. LIST label1,label2 lists all Basic lines between the two labels. List Label lists the Basic line that begins with 'label:'. LOAD "filename" This loads the file "filename" into Basic. The file can either be an Ascii file or a tokenized Basic file. Storm will figure out what type of file it is automatically. Loading a file erases any other program in memory. LOAD CAPTURE "filename" Loads the specified file into the capture buffer. LOAD TERM "file.emu" Load a terminal emulation module into Storm. Note that this just loads the terminal emulation; you need to use the MODE command if you want it to be the active emulation. There is no check to see if the emulation is already loaded. The maximum number of loaded terminal emulation modules is six, which doesn't include the built-in TTY terminal emulation. The STORM.INI profile file section [Terminal] contains a list of currently loaded terminal emulations. e.g.: [Terminal] Term1=C:\STORM\VT100.EMU Term0=C:\STORM\VIDTEX.EMU There is a memory-resident profile file names ENV which contains further information about loaded terminal emulation modules. The terminal emulations are listed by emulation names: [Terminal] Term1=VT100 Term0=VIDTEX The following code lists currently loaded terminal emulations. Note that the built-in terminal emulation TTY is always present. FOR i = 0 to 5 x$ = "Term" + STR$(i) PRINT i;"";SET$("STORM","Terminal",x$) PRINT i;" ";SET$("ENV","Terminal",x$) NEXT i ' Current emulation is listed by name under "Current" PRINT "Current=";SET$("STORM","Terminal","Current") LOAD XFER "file.trf" Loads a file transfer module into Storm. There is no check to see if the same module has already been loaded. The maximum number of loaded file transfer modules is six. (This doesn't include the Ascii file transfer, which is built-in). If you want to check to see what file transfer modules are present, there are several methods. First of all, the STORM.INI profile file section [Protocols] lists the currently loaded file transfer modules by filename. e.g.: [Protocols] Xfer2=C:\STORM\ZMODEM.TRF Xfer1=C:\STORM\XYMODEM.TRF Xfer0=C:\STORM\BPLUS.TRF Secondly, there is a memory-resident profile file named ENV which also contains information about loaded protocols. It contains two types of entries under the [Protocols] secton. The first type of entry, "Xfer0=name" lists the internal protocol name. The second type, "Popup0=name" lists the individual protocol names. e.g.: [Protocols] Xfer0=Bplus Xfer1=XYMODEM Xfer2=ZMODEM Popup0=Ascii Popup1=Xmodem Popup2=Xmodem-1K ... Popup6=Zm. Resume Note that the first popup name is always Ascii, which is an internal protocol. There are more protocol names than modules, since a module can contain several protocols. The following code example will list information about all loaded file transfer protocols. FOR i = 0 to 5 x$ = "Xfer" + STR$(i) PRINT i;"";SET$("STORM","Protocols",x$) PRINT i;" ";SET$("ENV","Protocols",x$) NEXT i ' FOR i = 0 to 11 x$ = "Popup" + STR$(i) print i;" ";SET$("ENV","Protocols",x$) NEXT i LOG Acts like Basic PRINT statement, but output is goes to the capture buffer. Still has a few quirks, for example it doesn't actually update the capture buffer display until a newline is printed. Also, the cursor is not repositioned in the capture buffer. LPRINT Prints to printer port using typical Basic syntax. MENU n1,n2 Allows a Basic program to simulate selecting a Storm menu item. n1 is the menu title index, where Desk=0, File=1, Edit=2, etc. An out of range menu title number will cause a Basic error. n2 is the item number in the menu dropdown, with the top item being number 1. Do not count separator lines as items. e.g. "Exit" is item number 10 in menu number 1. An out of range item number will be ignored. Disabled menu items will not be executed, since they were probably disabled for a good reason! This command is useful for programming ALT key macros. It is not possible to select desk accessories using the MENU statement. MERGE "filename" Loads the file "filename" and appends it to the end of the program in memory. "filename" must be an Ascii format file, not a tokenized file. MID$(dest$,start[,length]) = new$ Replaces a portion of destination string with a new string. dest$ is a string variable or a string array reference. new$ is a string which will be used to replace a portion of dest$. Length is an optional number specifying the number of characters to replace. Start is a number specifying the position where you want to start replacing. If length is not specified, then the length of the new$ string will be used, as long as it is not longer than the dest$ string. Note: The length of the destination string is never changed by this command; the replacement text just overwrites the specified portion of the destination string. If the new$ is shorter than length, then the length of new$ is used for replacement. MKDIR "dirname" Creates a folder (directory) using the specified name. An error will occur if dirname already exists or an invalid path is specified. MODE "name" Sets terminal emulations to "name", where "name" is the name of a loaded terminal emulation. No error is caused if the emulation is not found. If the terminal emulation is already the active emulation, it will be re-initialized. NEW Erases the program in memory, including all variables and arrays. NEXT Used in conjunction with the FOR statement. You can specify a loop variable, e.g. NEXT x, or leave it blank in which case NEXT will loop to the most recent FOR statement. You cannot use a list of variables, as in some Basics. e.g. NEXT x,y,z is not legal in Storm Basic. ON ON is used for a variety of purposes. The standard usage is to change the flow of control according to the result of an expression. ON expr GOSUB label1,label2,label3,... ON expr GOTO label1,label2,label3,... In these two cases, expr is any valid Basic expression, e.g. x+1, x/y or the name of a Basic variable. expr is evaluated and the result is used to determine which label to branch to. If the result is one, the first label in the list is used, if the result is two, the second label, and so forth. If the value is less than one or greater than the number of labels in the list, then control passes to the next statement. ON event(n) GOSUB label Event trapping Event trapping is a way of responding to events without having to constantly watch for them. When trapping is enabled on an event, Storm will check for the event between executing each statment and, if the event occurred, jump to a user-defined subroutine to handle the event. Multiple event traps are possible, though Storm blocks the current event from being trapped again while its trap routine is executing. Currently there are four events you can trap for; timer, carrier detect, serial port and clipboard. Event trapping can occur during executing of PAUSE, WAIT and KEYINPUT statements. It cannot occur during INPUT or LINE INPUT while Basic is waiting for a line of input in the Basic window or GEM functions such as POPUP, LISTBOX and FSEL$. ON TIMER(n) GOSUB Label TIMER ON TIMER OFF TIMER STOP TIMER CLEAR The statement ON TIMER(10) GOSUB Label tells the computer that every ten seconds it should branch to the subroutine at line Label. The timer value is checked between execution of each statement, and also checked during WAIT, PAUSE and KEYINPUT commands. The ON TIMER(n) gosub statement is actually a way of telling the computer to set up a timer event. To enable the event, you must also use TIMER ON. TIMER OFF disables event trapping. TIMER STOP is actually used by Basic internally to block the timer event during event processing. It stops event processing, but doesn't reset the timer count. Use TIMER OFF to disable the timer event. Warning: Do not reenable an event during the event subroutine. It can lead to unexpected results and may crash the program. TIMER CLEAR is used to erase the timer event trapping completely. ON CARRIER(n) GOSUB Label CARRIER ON CARRIER OFF CARRIER STOP CARRIER CLEAR Similarly, you can perform event trapping on the carrier detect signal. ON CARRIER(1)... waits for carrier detect to become TRUE, while ON CARRIER(0).. waits for loss of carrier. However, when you return from a carrier event trap, the trap sense is automatically reversed. ON CLIP(n) GOSUB Label CLIP ON CLIP OFF CLIP STOP CLIP CLEAR Clipboard event trapping lets you call a subroutine each time the user copies or cuts text to the clipboard from a STORM window. ON CLIP(n) selects clipboard trapping. The numeric parameter selects what type of clipboard selection to trap. CLIP(1) only traps copying from the terminal screen. CLIP(2) traps copying from the capture buffer window. CLIP(4) traps copying from any editing window, including the typeahead buffer and the capture buffer. As noted above, it is possible to have all events enabled simultaneously. You can also use WAIT or PAUSE or KEYINPUT during an event handling subroutine. As an example, you could have a PAUSE while executing a timer event subroutine. If a carrier event occurred during the pause, the carrier event subroutine would be executed, then the PAUSE would continue, then eventually the main program would continue. It is possible to short-circuit an event subroutine and jump to another line in the program. You should clear the event, use the POP statement to clean up the Basic stack, then GOTO to continue. If you want to continue the event trapping after this, you should re-enable the event completely by executing an ON event(n) GOSUB statement. One reason you might do this is if you had a carrier event enabled to detect loss of carrier during an online session. If carrier is dropped, you would not want to continue executing statments which wait for the other end to respond. If you forget the RETURN at the end of the event subroutine, execution will continue with the next line. If the event subroutine is at the end of the program, the program will end with no warning. More on event trapping. When an event trap jumps to a subroutine, it first saves the state of any WAIT, PAUSE, or KEYINPUT in progress. While in the event subroutine, no checking will be done for the pending WAIT, PAUSE, etc. However, you are free to use WAIT, PAUSE, or KEYINPUT during an event subroutine. When the event subroutine returns, the original WAIT, PAUSE, or KEYINPUT will be restored and can continue. If you set TERM OFF in your main program, then TERM will be off in the event subroutine unless you explicitly turn it on with TERM ON, or implicitly turn it on with a WAIT or PAUSE or KEYINPUT. ON COM(0) GOSUB Label COM ON COM OFF COM STOP COM CLEAR Use ON COM(0) to set up an event trap for the serial port. Whenever characters are available at the serial port, the specified subroutine is executed. You should use COMINPUT in the event subroutine to empty the serial port otherwise the event subroutine will be executed repeatedly. COM ON enables the event trap. COM OFF disables the event trap. COM CLEAR removes the event trap. OPEN "mode",#n,"filename" Opens a file in Basic. n is a digit from 1 to 15 which is the file number that is used in subsequent input # or print # commands. "mode" actually uses C language syntax. "mode" can be one of the following: "w" creates a text file for writing, discards previous contents. "r" opens a text file for reading. "a" append; opens or creates a text file for writing at end of file. "r+" opens text file for update (reading or writing). "w+" creates text file for update, discards previous contents. Adding a "b" to mode, e.g. "wb" opens the file in binary mode. Text mode is supposed to do CR->CR/LF translation so that a CR-LF combination in the file is replaced with a single line feed character when you read from the file, e.g. with LINE INPUT #n. When writing to a file in text mode, a carriage return is written as a carriage return followed by a line feed. PARITY ODD PARITY EVEN PARITY NONE Sets parity for the serial port, odd, even, or no parity. Word size is automatically set to 8 bits for no parity, 7 bits for even or odd parity. PAUSE nn Pauses execution for nn seconds. While the pause is in effect you are able to switch away from the Basic window. Terminal operation continues during the pause. Specifying -1 for the pause value generates the absolute maximum pause, which is over ten million seconds (about 124 days). Event trapping is enabled during PAUSE. The terminal window continues to receive and display characters if TERM is set to ON. PLAY string$ Uses the GEM Xbios function Dosound call. The sound values must have been read into a string variable or string array variable. A number of programs available through online services are able to generate appropriate data values for the Dosound function. Unfortunately, if the keyclick sound is enabled, pressing any key will abort Dosound. The same is true if the system bell sound is enabled and it is sounded. You should not alter the string variable contents while the sound is playing or unexpected results may occur. POP Pops a return value from the Basic runtime stack. Each time you call GOSUB or start a WHILE loop six bytes of return information are put on the Basic runtime stack. Exiting from a subroutine or WHILE loop by means of GOTO leaves this information on the stack. The stack will keep growing in this situation until you run out of memory. Use of POP is recommended to keep the stack small. You can also use POP if you exit from within a FOR/NEXT loop using a GOTO. This also leaves information on the stack. However, when you start a new FOR/NEXT loop with the same loop variable, any old reference to the same variable is removed from the stack automatically. PRINT Basic Print statement. Uses typical Basic syntax. However, PRINT USING is not supported. Neither is TAB(n) supported. Semicolons or commas are ALWAYS required between items to be printed. PRINT #n PRINT #n prints to a file where n is a file number of a file previously opened with the OPEN command. However, PRINT #0 will print directly to the terminal screen. PRINT #0 sends text to the terminal screen using the current terminal emulation, so that you can use escape sequences and other terminal emulation features. Text displayed in this manner is not sent out the serial port, nor is it detected by the WAIT or KEYINPUT commands. No linefeeds are added unless you use LFEEDS ON. READ var,var$,var(n),var$(n) Reads an item from a DATA statement into a Basic variable. You can read into any variable or array variable. Attempting to read a string value into an integer variable will cause an error. However, you can always read an integer value into a string variable; it just gets converted into the ascii representation of the value. REM Indicates a Basic comment. You can also use ' to start a comment. REPLACE$(dest$,start[,length]) = new$ Replace$ is a lot like MID$, except that it will expand or shrink the destination string. This means you can replace a part of string with a string that is a different length. Used REPLACE$ in place of awkward left$+"xxx"+right$ constructions to alter strings. Example: Generic replacement of "Street" with "St." a$ = "336 Queen Street South" ... ' Assume we don't know where "Street" starts or what case it's in. ' Use UCASE$ to create a copy of a$ that is uppercased. ' Search for "STREET" and replace in original a$ with "St." x = instr(UCASE$(a$),"STREET") if x then replace$(a$,x,6) = "St." print a$ This changes a$ to "336 Queen St. South". If you don't specify the replacement length, then it defaults to the length of that portion of the destination string from 'start' to the end of the string. e.g. in the above example, REPLACE$(a$,x) = "St." would change a$ to "336 Queen St.". Something like REPLACE$(a$,x,y) = "" is also permitted. It deletes the specified portion of the destination string. RESTORE RESTORE label RESTORE by itself resets the data pointer for subsequent READ operations to the start of the Basic program. You can use an optional label to restore the data pointer to a specific line. RETURN Returns from a GOSUB call. RMDIR "dirname" Deletes a subdirectory (folder). You cannot delete a subdirectory that contains files. You must delete all the files first. RUBOUT ON RUBOUT OFF RUBOUT / Sets the terminal Destructive Backspace setting. RUBOUT ON means that backspace characters (Ascii 8) received by the terminal cause the previous character on a line to be erased, unless the cursor is already in column zero, in which case nothing happens. RUBOUT / toggles the state of Destructive Backspace. RUN RUN "filename" RUN by itself just runs the program in memory. RUN "filename" loads a new program and then runs it. The program can be a tokenized Basic program or an Ascii Basic program. RUN always zeros variables and strings before the program starts. SAVE "filename" Saves the program in memory as a tokenized Basic file. This is a more compact format than Ascii, though it can only be read and understood by Storm Basic. Tokenized files also load faster than Ascii files. SAVE CAPTURE "filename" Saves the capture buffer to the indicated filename. If you want to be prompted with a file selector, use SAVE CAPTURE FSEL$("",""). SBITS 1 SBITS 2 SBITS 3 Sets the number of stop bits used by the serial port. SBITS 3 actually sets stop bits to one and a half (1.5) stop bits. SEND Acts the same as PRINT, except output is to the serial port instead of the Basic window. As with PRINT, SEND will automatically add a carriage return unless you end the statement with a semicolon or comma. You can send any control characters using SEND, including Ascii 0, by using CHR$(n). If half-duplex is set, characters will be echoed to the terminal screen. SET Used to set profile file settings. The current profile files are: STORM.INI Used for all Storm terminal settings. STORMKEY.INI Used to set keyboard macros. DIALDIR.INI The dial directory. The profile files are Ascii text files separated into sections. Each section is labelled with a name inside square brackets, followed by a number of entries of the type Setting=Value. Value can be an integer value or a string, or a quoted string. Profile files are loaded into memory when Storm runs and are saved when you exit, or can be saved manually from the menu bar. Some items in the profile file are only accessed when you first run Storm, others are accessed constantly. e.g. Keyboard macros are always retrieved from the STORMKEY.INI file in memory. Serial port settings are only retrieved from the profile file initially, though the profile settings are kept up to date each time the serial port settings are modified. Full documentation on the profile files will come at a later date. Example: to set the download path use: SET "STORM","Paths","DownloadPath","F:\DOWNLOAD\" The first string is the profile file name, minus the extension. The second string is the section name, the third string is the name of the item to be modified. The fourth string is the new value of the item. The fourth item can be a string or a integer. If the string contains control codes or begins with a quote character ("), it is automatically quoted and control codes converted into standard C language escape sequences. e.g. Ascii 10 becomes \n, Ascii 27 becomes \33, Ascii 127 becomes \177 You can create your own sections in the profile files for your own purposes and they will be created if they don't already exist. Currently only the predefined Storm profile files "STORM.INI", "STORMKEY.INI","DIALDIR.INI", and "HELP.INI" are fully supported. You can specify another profile file name and access entries in it, but it will exist only in memory. It will not be loaded (even if it exists) and it will not be saved to disk. Profile sections items are case-sensitive. You must type the names exactly as they appear in the profile file. STOP Stops the program. You can restart the program with CONT. Variables remain unaffected. STRIP ON STRIP OFF STRIP / Sets whether the high bit is masked off when reading from the serial port. Useful when connecting to a system transmitting parity when you have parity off. STRIP / toggles the current setting. TA ON TA OFF TA / Turns typeahead on or off, or toggles the state of typeahead. When typeahead is turned on, a cursor is displayed in the typeahead window and you can enter text there. TERM ON TERM OFF Normally, when Storm and Basic are running, the terminal window and Basic program execution proceed in parallel. This means that under some circumstances, you can miss a string you are waiting for because Basic is executing another line of code while the terminal is processing serial input. So when a WAIT statement comes up again, the string has already been processed by the terminal. This is only a problem when the strings are separated by very short pauses. In order to cure this, you can use the TERM statement to shut off terminal processing except during WAIT statements. This will guarantee that every single character that comes in the serial port will get checked by the WAIT statement. If that's what you want, use TERM OFF where you want strict serial port checking to start, and TERM ON where you don't really care. TERM is ON by default and is automatically turned back on when a Basic program is stopped or ends. It is also turned on during WAIT, PAUSE, and KEYINPUT commands. For example, if you want to catch prompts between each message at 9600 baud, use TERM OFF. If you only want to catch the prompt at the end of a process that will take a while, leave term on. TIMER ON TIMER OFF TIMER STOP TIMER CLEAR See description of timer events under event trapping. TOPW TOPW n TOPW by itself brings the Basic window to the top. TOPW followed by a number brings the specified window to the top. The window number is based on the Windows menu dropdown. 1 is the Terminal window 2 is the Capture window 3 is the Basic window 4 through 10 are editing windows (only topped if actually open) 11 is the file transfer window (only topped if open) TRAP label Generates an error trap so that when a Basic error occurs, Basic will do a gosub to the label in the trap statement. Currently return from the trap routine should be by a RETURN statement to continue execution by re-executing the statment that generated the error. Or, you can do a POP statement to pop the return off the stack and then GOTO any other line. ERR(0) returns the Basic error number (listed elsewhere). ERR(1) returns the line number in which the error happened. Line numbers for this purpose start at one for the first line in the file. After the trap routine is entered, you need to reset the trap handler with another TRAP statement before proceeding. TRON TROFF Turn tracing on or off. This can be done inside a program, from the Ready prompt, or the Basic menu dropdown. When tracing is enabled, line numbers inside square brackets are printed as each line is executed. As with the TRAP statement, Basic programs are numbered sequentially, starting at line one. TYPE UNLOAD XFER "name" UNLOAD TERM "name" Unloads a file transfer (XFER) or terminal emulation (TERM) from memory. Use the name that appears in the Terminal Emulations or Transfer Protocols dialog box. e.g "VT100" or "ZMODEM". See "LOAD XFER" and "LOAD TERM" for code showing how to find the names of currently loaded file transfers and terminal emulations. Note that unloading a terminal emulation sets emulation to the default TTY emulation. Be sure to reset terminal emulation with the MODE command afterwards. If the module is not found, no error occurs. WAIT nn,"string"[,"string",...] This is the most important command for automated operation. You can wait for multiple strings with a timeout value (in seconds). Basic will match characters coming in the serial port with the strings and continue with the next statement when either the string is matched, or a timeout occurs. Naturally, all program functions are enabled while the wait is in progress. A timeout value of -1 waits forever (actually, about 124 days). Once the WAIT statment has executed, use the WAIT(0) function to determine the result. WAIT(0) returns 0 if there was a timeout, otherwise it returns the string number that was matched, starting at 1 for the first string. So you could use ON WAIT (0) GOSUB 100,200,300,etc. WHILE expr statements WEND While the expression evaluates to TRUE, executes the statements inside the loop. If the expression is FALSE, skips to the next statement past the WEND statement. A WHILE/WEND block can span multiple lines and can begin or end in the middle of a line. =========================================================== Basic functions and operators Functions in Storm Basic generally take a set of arguments and return a value. Functions whose name ends in a dollar sign ($) returns a string value. All other functions return a numeric value. All numbers in Storm Basic are 32-bit signed values. Certain keywords like CLIP$, CARRIER, and CSRLIN return a value but, unlike true functions, have no arguments. ABS(n) Basic function returns the absolute value of a single numeric argument. ALERT(1,"[1][alert][OK]") Lets you display a standard GEM alert box. The number is the number of the default button. The string must be a proper GEM alert string. No checking is done of the string. The return value is the number of the button that was selected. AND Performs a bitwise Boolean AND operation between two numeric values. ASC("x") Function which returns the Ascii value of the first letter of a string parameter. CAP$(n) String function which returns a line of text from the capture buffer. The numeric parameter indicates which line to return. The first line of the capture buffer is line number one. An out of range number will return an empty string. A blank line will also return an empty string. The line of text is not terminated by a carriage return or line feed. CAPTURE Returns TRUE if Capture is enabled, otherwise FALSE. No parameters are required. e.g. PRINT CAPTURE will print -1 if Capture is enabled or 0 if it is not. CARRIER Returns TRUE if the carrier detect signal on the serial port is on, otherwise returns FALSE. No parameters are required. This function works on all TT, MegaSTE and Falcon serial ports CHR$(n) Returns a string consisting of a single character with the Ascii value of the numeric parameter. CAPTURE CLEAR Clears the capture buffer. CLIP$ CLIP$ returns the contents of the clipboard. If the clipboard is empty, CLIP$ returns the empty string "". The maximum size of CLIP$ is 65535 bytes. CLIP$ can consist of multiple lines, separated by a line feed character. Even if you select a single letter, the program will still add a line feed to it, so always be prepared to strip out the line feed character, e.g. with RTRIM$. CSRLIN Returns the terminal screen cursor row location. No parameters required. The top line of the terminal screen is line 1. DATE$ DATE$ returns the date as a string in the format mm-dd-yyyy DFREE("A") Returns free space on a drive. The parameter is a string consisting of drive letter you want information on. DLOAD("protocol","file",...) Example: x = DLOAD("XMODEM","FILE") This downloads the file "FILE" using the Xmodem protocol. The 'x' will contain the number of files actually transferred, in this case '1' if successful, '0' if there was an error. If you omit the filename, the protocol module will automatially put up a file selector if required by that protocol. If you abort the transfer, the return value will be 0. If you abort the Basic program, the file transfer will continue. Protocol names should be the same names as listed when downloading via the File menu. Upper and lower case are not significant. Basic will search through the list of available protocols. If the protocol is not found, a Basic error will result. You can use multiple filenames, but non-batch protocols, e.g. xmodem, will only transfer the first file. Wildcards are NOT permitted in the filenames. However, you could expand wildcards using the Basic functions FSFIRST$ and FSNEXT$. DRVMAP$ Returns a string with letters indicating which drives are available on the system. e.g. "ABCDE" indicates drives A through E. The letters are always uppercase. Note that 'A' and 'B' can both be present, even if the system has only a single floppy drive because GEM can simulate drive B internally. ENVIRON$("name") Returns the value of an environment variable. The parameter is the name of the environment variable (environment string) you want information about. A nonexistent variable returns an empty string. EOF(n) Returns TRUE of the end of a file has been reached. Used when reading a file to detect the end of the file. 'n' is the file number. ERR(0) Returns the Basic error number of the most recent Basic error. Current error numbers and error messages: 0 "Unknown Error" (or no error at all) 1 "Expression too complex" 2 "Invalid NEXT" 3 "NEXT without FOR" 4 "Invalid RETURN" 5 "Out of data on READ" 6 "Illegal parameters" (fairly generic error) 7 "No more variables (max 128)" 8 "Out of memory" 9 "Undefined line number" 10 "Subscript out of range" 11 "Attempt to redimension" 12 "Out of string space" 13 "Bad load file format" 14 "File I/O error" 15 "Can't open file" 16 "Can't write file" 17 "Can't read file" 18 "Stack Underflow" 19 "Divide by zero" 20 "ELSE without IF" 21 "WHILE without WEND" 22 "WEND without WHILE" 23 "Syntax errors during load" 24 "Error token encountered" 25 "String too large" 26 "Badly formed label" 27 "Duplicate Label" 28 "Wrong Data Type" 29 "ENDIF must be at start of line" 30 "IF must be at start of line" 31 "ENDIF without block if" 32 "ELSE without block if" ERR(1) Returns the line number where the last error occurred. Basic programs are numbered internally starting at line 1. FRE(n) Because Basic allocates and deallocates memory as needed, most FRE calls return how much memory is used, not how much is free. Most of these values are only useful for debugging purposes. FRE(3) returns the number of characters waiting in the serial buffer. It is somewhat useful when figuring out if you are at a prompt, but not 100% effective with time-sharing systems, where long pauses are not uncommon. FRE(2) returns the number of bytes in the capture buffer. It does this by counting the number of characters in each line. It does not take account of any overhead used to keep track of the capture buffer. FRE(1) returns the number of lines in the capture buffer. It will always be at least 1, because there is always at least a single blank line. FRE(0) returns the largest available free memory block in the system, that is, the result of calling Malloc(-1L) FRE(-1) returns total space used for strings (not including system overhead). FRE(-2) returns the total number of string slots currently allocated. This is never less than 16. FRE(-3) returns the number of strings currently in use. FRE(-4) returns the number of bytes used for storing the current program statements. FRE(-5) returns the size in bytes of the variable name table. Each variable name is stored as a null-terminated string. There are two extra null bytes to mark the end of the table. FRE(-6) returns the size in bytes of the variable value table. Each variable takes 8 bytes of storage. FRE(-7) returns the size in bytes of the array table. Each element of an array takes 4 bytes in this table. FRE(-8) returns the size of the run-time stack. This is typically 64 bytes, unless you have very deeply nested loops. FRE(-9) returns the number of labels in the label table. FRE(-10) returns the size in bytes of the label name table. FRE(-11) returns the number of bytes allocated to the capture buffer. This is usually more than the number of bytes actually used. Mostly of academic interest. Any other value inside the brackets returns the same as FRE(0). FSEL$("path","filename") Pops up the GEM file selector and returns a filename. "path" lets you specify the path to be displayed by the file selector. An empty path ("") will cause the default path to be used. A path starting with a backslash will be in the root of the default path's drive. A path with a colon character (:) as the second character is used as-is. Any other path is appended to the current path. You should either end the path with the wildcard you want to use, or end it with a backslash, in which case the default wildcard "*.*" will be added. Or, use just a wildcard to have it added to the default path. e.g. FSEL$("*.BAS",""); "filename" is the filename to be displayed in the file selector. A blank filename is permitted. e.g. FSEL$("","") just pops up a file selector with current path and default wildcard "*.*" and an initially empty filename. If you select Cancel then FSEL$ returns an empty string. If you select OK, but the filename is blank, then an empty string is returned. FSELPATH$("path") Pops up the GEM file selector and returns the path only. If you select Cancel, it returns an empty string. "path" lets you specify a starting path. "path" should be a full path including drive letter and should end with a backslash, An empty path ("") will cause the default path to be used. FSFIRST$("filespec",mask) FSNEXT$ These calls are used to get a directory into string variables. FSFIRST$ corresponds to the GEMDOS Fsfirst call. The filespec is a wildcard value, which can include a full directory path. mask is an integer value representing which files you wish to view. The mask values are: 1 File is read-only 2 File hidden from directory search 4 File set to "system" 8 Volume label 16 Directory 32 "Archive bit" meaning file has been updated. Add the mask values together to generate an appropriate mask. You are best of always specifing the "Archive bit" because you never know what state it is going to be in. The DIR command uses a mask of 49, which is equal to 32+16+1. Note that FSFIRST$ and FSNEXT$ will return the two directory entries of '.' and '..' which are found in every directory and are used by TOS internally. Once you call FSFIRST$, then keep calling FSNEXT$ until it returns an empty string. Example: This prints out the current directory. PRINT FSFIRST$("*.*",31) X = 1 WHILE X a$ = FSNEXT$ IF a$ = "" THEN X = 0 ELSE PRINT a$ WEND Sample output: ----d- 0 1991/06/06 11:00:00 AUTO -----a 123 1992/08/25 12:12:11 DESKTOP.INF The first six characters are file attributes. The possible attributes (in order of appearance) are: r = Read Only h = Hidden File s = System File v = Volume Label d = Directory a = Archive Bit Any attribute not present is replaced with a '-'. The attributes are followed by a single space, then a ten character field for the file size, then the date, time and filename as shown above. The fixed size fields make it easy to extract desired information using the MID$ function. INSTR([start,]"string","key") This is a string search function. It searches "string" for substring "key" and returns the location of "key" in "string", or 0 for failure. 'start' is optional and is the location in the string to start at. N.B. The first location in a string is location 1. Also, no matter where you start searching in the string, INSTR always returns an index relative to the start of the string. Example: INSTR("12345","3") and INSTR(3,"12345","3") both return 3. ISDIGIT("string") Returns TRUE if the first character of the string argument is a digit. Returns FALSE if it is not a digit. LCASE$("string") Returns a copy of a string converted to all lowercase characters. LEFT$("string",n) Returns a string containing the leftmost n letters of the string. LEN("string") Returns the length of a string. LISTBOX(title$,array$(n),count) This is a new GEM based method of asking for user input. The listbox displays a list of text items in a box with slider, scroll bar, arrows, and a title. The number of items that can be used in a listbox is limited only by Basic memory limits. The listbox call returns the index of the item selected (starting with 1) or zero if no item was selected. title$ is a string or string expression which is used as the title for the listbox. array$(n) is the starting array location for the start of the listbox data. Count is the number of items from the array to use in the listbox. Count must be an integer constant or integer variable. Using an array that is smaller than the count value may produce unexpected results! When the listbox is on screen, you can move up and down the list of items using the cursor keys or the mouse. Select an item with the mouse or by pressing Return. Cancel by pressing Undo. Autosearch The listbox has a special property such that if you press a key, it will search forward for the next item which starts with that key. This is very useful for large lists. I recommend that you use sorted lists to benefit most from this feature. LTRIM$("string") Returns string, stripped of leading 'white space' characters. 'white space' characters include space, formfeed, newline, carriage return, tab, and vertical tab. MID$("string",s,n) Returns the substring of "string" starting at location s and continuing for n letters. n is optional. Omitting n returns the string starting from location s. The first letter in a string is considered to start at position 1. MOD This is the modulus operator. It calculates the remainder obtained from an integer division of two numbers. e.g. The result of 11 MOD 8 is 3. NOT Operator which performs a bitwise negation of a number. OR Operator which performs a bitwise OR of a number. POPUP(n,"Title"," Item 1"," Item 2",...) POPUP is a function call which displays a popup menu on the screen which the user can select an item from. POPUP returns 0 if nothing was selected, otherwise it returns the number of the item that was selected, starting with 1 for the first item in the list. The first value in the function call is a numeric value. If it is greater than zero, then the corresponding menu item will be displayed with a check mark. I sugges that you leave two leading spaces in front of each menu item to allow room for the check mark. The title is a string which is displayed at the top of the popup menu, in its own box. It is always centered in the box and does not require any leading or trailing spaces, but you can add them if you wish. The width of the popup is always that of the widest item. The menu items can be string variables or string array items, they do not have to be quoted text. Popup menus are more suitable for displaying choices than alert boxes and a lot easier to use. For large lists of items, use LISTBOX. POS(0) Returns the terminal screen cursor column location. The argument is a dummy argument. It may seem odd that CSRLIN (with no argument at all) is used for the cursor row and POS(0) (with a useless argument) is used for the cursor column. Well, this is the way it's done on the IBM PC, so I have just copied their way of doing things for compatibility. PROMPT$(n) This function takes up to n characters from before the current terminal screen cursor position and returns it as a string. Doesn't go past the beginning of the current line. Useful for getting the current prompt when automating operations. RIGHT$("string",n) Returns the rightmost n letters of the string. RND(n) Returns a random number between 0 and 32767. If the argument is non-zero, seeds the random number generator with that value. RTRIM$("string") Returns string, stripped of trailing 'white space' characters. 'white space' characters include space, formfeed, newline, carriage return, tab, and vertical tab. SCREEN$(n) Returns a line of text from terminal screen line 'linenumber'. The first line of the screen is 1. Trailing whitespace is stripped from the line, so a blank line is returned as an empty string "". SET("file","section","name") SET$("file","section","name") Returns the value of an item in the specified profile file. SET returns a numeric value, while SET$ returns a string. If the item does not exist, then SET$ will return an empty string, while SET will return zero. Current profile filenames are "STORM", "STORMKEY", "DIALDIR" and "HELP". The ".INI" extensions are not used. SGN(n) Returns -1 if n is negative, +1 if n is positive. SPACE$(n) Returns a string of n spaces. STR$(n) Returns an string representation of a number n. e.g. STR$(9) returns "9". TIME$ Returns the time as a string in the format hh:mm:ss TIMER Returns the time (in seconds) since the program started running. This is actually the standard C library function clock(). Reasonably useful for timing things. UCASE$("string") Returns a copy of a string converted to all uppercase characters. ULOAD Example: x = ULOAD("XMODEM","FILE") This uploads the file "FILE" using the Xmodem protocol. The 'x' will contain the number of files actually transferred, in this case '1' if successful, '0' if there was an error. If you omit the filename, the protocol module will automatially put up a file selector if required by that protocol. If you abort the transfer, the return value will be 0. If you abort the Basic program, the file transfer will continue. Protocol names should be the same names as listed when uploading via the File menu. Upper and lower case are not significant. Basic will search through the list of available protocols. If the protocol is not found, a Basic error will result. You can use multiple filenames, but non-batch protocols, e.g. xmodem, will only upload the first file. Wildcards are NOT permitted in the filenames. However, you could expand wildcards using the Basic functions FSFIRST$ and FSNEXT$. VAL("12345") Converts an Ascii string into a (long) number. WAIT(0) WAIT(0) returns 0 if there was a timeout, otherwise it returns the string number that was matched by the most recent WAIT statement, starting at 1 for the first string. XOR Performs an exclusive xor operation on two numbers. Reserved Basic keywords The following Basic commands and functions are currently unimplemented but the keywords are reserved for future expansion. NOTE, POINT, GET, PUT, ECHO, HCOPY, HANGUP, and DIAL.